 /*******************************************************************************
  * Copyright (c) 2000, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.core.runtime;

 /**
  * A status object represents the outcome of an operation.
  * All <code>CoreException</code>s carry a status object to indicate
  * what went wrong. Status objects are also returned by methods needing
  * to provide details of failures (e.g., validation methods).
  * <p>
  * A status carries the following information:
  * <ul>
  * <li> plug-in identifier (required)</li>
  * <li> severity (required)</li>
  * <li> status code (required)</li>
  * <li> message (required) - localized to current locale</li>
  * <li> exception (optional) - for problems stemming from a failure at
  * a lower level</li>
  * </ul>
  * Some status objects, known as multi-statuses, have other status objects
  * as children.
  * </p>
  * <p>
  * The class <code>Status</code> is the standard public implementation
  * of status objects; the subclass <code>MultiStatus</code> is the
  * implements multi-status objects.
  * </p><p>
  * This interface can be used without OSGi running.
  * </p>
  * @see MultiStatus
  * @see Status
  */
 public interface IStatus {

     /** Status severity constant (value 0) indicating this status represents the nominal case.
      * This constant is also used as the status code representing the nominal case.
      * @see #getSeverity()
      * @see #isOK()
      */
     public static final int OK = 0;

     /** Status type severity (bit mask, value 1) indicating this status is informational only.
      * @see #getSeverity()
      * @see #matches(int)
      */
     public static final int INFO = 0x01;

     /** Status type severity (bit mask, value 2) indicating this status represents a warning.
      * @see #getSeverity()
      * @see #matches(int)
      */
     public static final int WARNING = 0x02;

     /** Status type severity (bit mask, value 4) indicating this status represents an error.
      * @see #getSeverity()
      * @see #matches(int)
      */
     public static final int ERROR = 0x04;

     /** Status type severity (bit mask, value 8) indicating this status represents a
      * cancelation
      * @see #getSeverity()
      * @see #matches(int)
      * @since 3.0
      */
     public static final int CANCEL = 0x08;

     /**
      * Returns a list of status object immediately contained in this
      * multi-status, or an empty list if this is not a multi-status.
      *
      * @return an array of status objects
      * @see #isMultiStatus()
      */
     public IStatus[] getChildren();

     /**
      * Returns the plug-in-specific status code describing the outcome.
      *
      * @return plug-in-specific status code
      */
     public int getCode();

     /**
      * Returns the relevant low-level exception, or <code>null</code> if none.
      * For example, when an operation fails because of a network communications
      * failure, this might return the <code>java.io.IOException</code>
      * describing the exact nature of that failure.
      *
      * @return the relevant low-level exception, or <code>null</code> if none
      */
     public Throwable getException();

     /**
      * Returns the message describing the outcome.
      * The message is localized to the current locale.
      *
      * @return a localized message
      */
     public String getMessage();

     /**
      * Returns the unique identifier of the plug-in associated with this status
      * (this is the plug-in that defines the meaning of the status code).
      *
      * @return the unique identifier of the relevant plug-in
      */
     public String getPlugin();

     /**
      * Returns the severity. The severities are as follows (in
      * descending order):
      * <ul>
      * <li><code>CANCEL</code> - cancelation occurred</li>
      * <li><code>ERROR</code> - a serious error (most severe)</li>
      * <li><code>WARNING</code> - a warning (less severe)</li>
      * <li><code>INFO</code> - an informational ("fyi") message (least severe)</li>
      * <li><code>OK</code> - everything is just fine</li>
      * </ul>
      * <p>
      * The severity of a multi-status is defined to be the maximum
      * severity of any of its children, or <code>OK</code> if it has
      * no children.
      * </p>
      *
      * @return the severity: one of <code>OK</code>, <code>ERROR</code>,
      * <code>INFO</code>, <code>WARNING</code>, or <code>CANCEL</code>
      * @see #matches(int)
      */
     public int getSeverity();

     /**
      * Returns whether this status is a multi-status.
      * A multi-status describes the outcome of an operation
      * involving multiple operands.
      * <p>
      * The severity of a multi-status is derived from the severities
      * of its children; a multi-status with no children is
      * <code>OK</code> by definition.
      * A multi-status carries a plug-in identifier, a status code,
      * a message, and an optional exception. Clients may treat
      * multi-status objects in a multi-status unaware way.
      * </p>
      *
      * @return <code>true</code> for a multi-status,
      * <code>false</code> otherwise
      * @see #getChildren()
      */
     public boolean isMultiStatus();

     /**
      * Returns whether this status indicates everything is okay
      * (neither info, warning, nor error).
      *
      * @return <code>true</code> if this status has severity
      * <code>OK</code>, and <code>false</code> otherwise
      */
     public boolean isOK();

     /**
      * Returns whether the severity of this status matches the given
      * severity mask. Note that a status with severity <code>OK</code>
      * will never match; use <code>isOK</code> instead to detect
      * a status with a severity of <code>OK</code>.
      *
      * @param severityMask a mask formed by bitwise or'ing severity mask
      * constants (<code>ERROR</code>, <code>WARNING</code>,
      * <code>INFO</code>, <code>CANCEL</code>)
      * @return <code>true</code> if there is at least one match,
      * <code>false</code> if there are no matches
      * @see #getSeverity()
      * @see #CANCEL
      * @see #ERROR
      * @see #WARNING
      * @see #INFO
      */
     public boolean matches(int severityMask);
 }

